RESTful APIとRESTful Webサービス
REST APIがよく利用される理由
昨今のWebサービスはほとんどが階層構造になっていています。基本的なデータベース操作などを含むビジネスロジックをバックエンド側が API で提供し、フロントエンド側でそれらを魅力的なアプリケーションとして実装するといった開発が主流になっています。
API(Application Programming Interface) はサービス提供者が、そのサービスを利用するために提供するインタフェースでこれまでにもSOAPのようなWeb APIと呼ばれるものも存在していました。REST API はHTTPの基本記述を用いてより汎用的に利用できるため、広く使われるようになりました。
REST APIとRESTful APIについて
REST (REpresentational State Transfer)は、Roy Fieldingが2000年に提唱した分散型システムにおける複数のソフトウェアを連携させるための設計原則（設計の考え方）です。
このRESTの考え方に従って設計されたAPIを REST API と言います。
RESTFul API は RESTの制約に従っていて "RESTらしいAPI" という意味で、ほとんど同義語として、どちらも使われます。
REST API は個別にアドレス指定可能なリソース（API の名前）の集合としてモデル化されます。リソースはそのリソース名で参照され、メソッド（オペレーション）によって操作されます。例えば、HTTPプロトコルでは、リソース名は URLにマッピングされ、メソッドは HTTPメソッド(POST、GET、PUT、PATCH、DELETE)にマッピングされます。
REST APIに基づいたアプリケーションの開発者は、それらが少数の標準的なメソッドを持っているという前提で、リソースとメソッドとの関係を実装することに注力できるため、開発工数を大きく削減することができます。
リソース指向アーキテクチャ(ROA: Resource Oriented Architecture) は、参照するものを「リソース」として定義し、そのリソースを中心に考えるアーキテクチャのことをいいます。
ROAはRESTful APIを実装するときに標準となるアーキテクチャになります。
REST APIの実用例
実際にサービス提供されているREST APIは多数ありますが、以下はそのほんの一例です。
よく設計されているAPIの仕様を読むことはとても学習にとって有益です。
REST APIの制約
REST API では次の6つの制約（設計ルール）によって定義されます。
1. クライアントサーバー(Client-Server)：
サービスを提供するサーバーとそれを利用するクライアントが分離されています。
2. ステートレス(Stateless)：
クライアントからのリクエストには、サーバーがそれを処理するために必要なすべての情報が含まれている必要があります。つまり、サーバーは、クライアントからの１つのリクエストに対して提供された情報を保存して、別のリクエストで使用することはできません。このため、セッション状態に関する情報はクライアントが保持します。もっと簡単に言うと、個々のリクエストは完結しているということです。
3. キャッシュ可能(Cacheable)：
サーバーは、リクエストをキャッシュできるかどうかをクライアントに示す必要があります。
キャッシュは、クライアントとサーバー間のやりとりの一部を不要にします。
4. 階層型システム(Layered System)：
クライアントとサーバー間のやりとりは、追加のレイヤーによって仲介することができます。
これらのレイヤーにより、ロードバランシング、共有キャッシュ、またはセキュリティなどの追加機能を提供できます。
クライアントはこのことについて何もする必要はありません。
5. 統一されたインターフェース(Uniform Interface)：
クライアントとサーバー間の通信方法は統一されている必要があります。
情報の操作(取得、作成、更新、削除)は全てHTTPメソッド(GET、POST、PUT、DELETE)を利用するようにします。
6. コードオンデマンド(Code on demand)：
サーバーは、クライアントがコンテキストで実行するための実行可能コードまたはスクリプトを提供することでクライアントの機能を拡張することができます。
この制約だけはオプションです。
統一インタフェース
あなたの作成するAPIのインターフェイスを統一したものにすることで、開発者が、ひとつのAPIに習熟すれば、他のAPIも容易に理解できるようになります。
URI
REST API で提供するリソースには、固有のURIを1つだけ持たせるようにします。
URI(Uniform Resource Identifier) は、http、https や ftp などのスキームに続けて、コロン (:) による区切りのあとにスキームごとに定義された書式に従ってリソースを示すもので、URL(Uniform Resource Locator) の考え方を拡張したものです。
リソースの表現
RESTにはリクエストで提供されるデータやサーバからのレスポンスのボディーの形式には制約はありませんが、一般に、REST APIでのクライアントとサーバ間のデータの受け渡しには、軽量なデータ形式であるJSONが使用されます。
リクエスト時に、URLのクエリ文字列部分の引数としてサーバへ提供される場合もあります。
リソースのリンクと接続性
すべてのリソースは、HTTPプロトコルの GET など一般的な方法でアクセスできるようにし、それらを正しく使い分けて一貫したものとしましょう。
命名規則、リンク形式、データ形式には統一したルールをもたせるようにしましょう。
OpenAPI
REST API を定義する共通規格として OpenAPI 仕様が登場しました。 OpenAPI を使用すると、開発者は言語に依存せずに REST API インタフェースを
構築できるようになります。
RESTful Webサービス
RESTアーキテクチャはもともと、World Wide Webが使用するHTTPプロトコルに適合するように設計されていることもあり、Web技術との親和性は高くなります。
RESTful Webサービスの概念の中心にあるのはリソースです。 リソースはURIで表されます。 クライアントは、HTTPプロトコルで定義されたメソッドを使用してこれらのURIにリクエストを送信し、その結果として、影響を受けるリソースの状態が変化します。
HTTPリクエストメソッドは通常、特定のリソースに標準的な方法で影響を与えるように設計されています。
table: WEB
HTTPメソッド 操作 URIの例
GET
URIで指定したリソースやリソースの一覧を取得するときには、GETメソッドを使います。
APIサーバはレスポンスのボディにリソースを表現して送信します。
PUT
リソースを追加したり、更新したりするときにPUTメソッドを使用します。
リソースを追加する場合URIはクライアント側が指定することになります。
リソースの一部分を更新するときはPATCHが使われることもあります。
POST
URIで指定した親リソースに対して子リソースを追加するときにPOSTメソッドを使用します。
リソースのURIはサーバが決定することになります。
リソースを作成する場合、特別な理由がないかぎりリソースの作成はPOSTを使うようにしましょう。
DELETE
リソースを削除したいときにはDELETEメソッドを使います。このとき、レスポンスのボディにはステータスメッセージを含んでいるか空となります。
HEAD
リソースのサイズ、更新日時などのリソースのメタデータを取得するときにHEADメソッドを使います。これは、HEADメソッドのレスポンスにはボディが含まれないので応答性がよくなるためです。
OPTIONS
リソースがサポートしているメソッドを調べるようなときにOPTIONSメソッドを使います。
OPTIONSメソッドのレスポンスにはAllowヘッダーが含まれるため、そこを参照することでサポートされているメソッドを知ることができます。
URIの設計
リソースを指定するためのURIをうまく設計しておくことが重要です。
APIバージョンを含める
URIにAPIバージョンを含めるようにしておくと、将来APIバージョンが変わったようなときでも簡単に対応が可能になるだけでなく、下位互換も保つことができるようになります。
APIのためのURIであることがすぐに判別できるようにしておきましょう。
http://api.example.com/v1/resource
http://www.example.com/api/v1/resource
動詞を含めない
リソースを取得する場合、/get/resourceのようにURI中に操作を表す動詞(get)を含めずに、/resource のようにしてHTTPプロトコルのGETメソッドを利用するようにします。
こうすることで統一されたインタフェースとなります。
拡張子を含めない
URIに.exe や .php などアプリケーションや言語に依存する拡張子は含めないようにします。将来APIのバージョン更新にともない使用する言語やプラットフォームが変わらないとも限りません。
リソースの関係性を表現する
リソースがどこに属しているものかを明確するようにします。
例えば、タスク管理のためのAPIであれば次のようなURIにします。
http:/www.example.com/todo/api/v1/
ただし、長すぎても面倒になるだけですし、そもそも覚えるのも大変になります。
REST APIではそれを使った開発者もいることを心に留めておきましょう。
レスポンスステータス
Webサーバーに対して行われたすべてのリクエストにはステータスコードが返されます。
ステータスコードは、リクエストで発生した内容に関する情報を示しています。
例えば、GETリクエストに関連するいくつかのステータスを次に示します。
200 —すべてが問題なく実行されました。結果がある場合は正常に返されました。
301—サーバーが別のエンドポイントにリダイレクトしています。
401 —サーバーはあなたが認証されていないと考えています。
APIにアクセスするための適切な認証情報を送信しない場合に発生します
400 —サーバーはあなたが誤ったリクエストをしたと考えます。
これは、特に適切なデータを一緒に送信しない場合に発生する可能性があります。
403—アクセスしようとしているリソースは禁止されています
リソースを表示するための適切な権限がありません
404 —アクセスしようとしたリソースがサーバー上に見つかりませんでした。
RESTful Webサービスでもこれらのステータスを返すことになります。
参考：